.\" Copyright (c) 2013-2018 Julien Nadeau Carriere <vedge@csoft.net>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd March 16, 2013
.Dt AG_USER 3
.Os
.ds vT Agar API Reference
.ds oS Agar 1.3
.Sh NAME
.Nm AG_User
.Nd agar user account information interface
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
.Ed
.Sh DESCRIPTION
.Nm
provides a cross-platform method for accessing information about user accounts.
Different backends may be implemented (see
.Sx INTERNAL API
below).
Agar provides the following backends:
.Pp
.Bl -tag -compact -width "agUserOps_posix "
.It agUserOps_dummy
No-op, returns no useful information.
.It agUserOps_getenv
Use the
.Va USER ,
.Va UID ,
.Va EUID ,
.Va HOME
and (optional)
.Va TMPDIR
environment variables.
Only
.Va USER
can be queried.
.It agUserOps_posix
On Unix, use
.Xr getpwent 3
or
.Xr getpwnam_r 3 .
Since accessing the password database incurs startup overhead, "getenv" is
the actual default unless the
.Dv AG_POSIX_USERS
flag is passed to
.Xr AG_InitCore 3 .
.It agUserOps_win32
On Windows, use CSIDL to locate a preferred
.Pa AppData
directory, and return it in the
.Va home
field.
Also return the preferred temporary directory in the
.Va tmp
field.
Other fields will contain no useful data.
.It agUserOps_xbox
On the Xbox console, check which drives are mounted and use
either T:\\ or D:\\ as home.
.El
.Sh INTERFACE
.nr nS 1
.Ft "AG_UserNew *"
.Fn AG_UserNew "void"
.Pp
.Ft "AG_User *"
.Fn AG_GetUserByName "const char *name"
.Pp
.Ft "AG_User *"
.Fn AG_GetUserByUID "Uint32 uid"
.Pp
.Ft "AG_User *"
.Fn AG_GetRealUser "void"
.Pp
.Ft "AG_User *"
.Fn AG_GetEffectiveUser "void"
.Pp
.Ft "void"
.Fn AG_UserFree "AG_User *"
.Pp
.Ft void
.Fn AG_SetUserOps "const AG_UserOps *ops"
.Pp
.nr nS 0
The
.Fn AG_UserNew
function returns a newly-allocated
.Nm
structure.
This structure is defined as:
.Bd -literal
typedef struct ag_user {
	char	 name[AG_USER_NAME_MAX];  /* User name */
	Uint     flags;
#define AG_USER_NO_ACCOUNT 0x01           /* Not a real user account */
	char    *passwd;                  /* Encrypted password */
	Uint32   uid;                     /* User ID */
	Uint32   gid;                     /* Group ID */
	char    *loginClass;              /* Login class */
	char    *gecos;                   /* Honeywell login info */
	char    *home;                    /* Home directory */
	char    *shell;                   /* Default shell */
	char    *tmp;                     /* Temp. directory */
	AG_TAILQ_ENTRY(ag_user) users;
} AG_User;
.Ed
.Pp
The
.Fn AG_GetUserByName
and
.Fn AG_GetUserByUID
functions look up a user account by name string, or numerical identifier.
.Pp
The
.Fn AG_GetRealUser
and
.Fn AG_GetEffectiveUser
functions return account information for the user corresponding to
the real or effective UID of the calling process (if available).
.Pp
The
.Fn AG_UserFree
routine releases the specified
.Nm
structure.
.Pp
The
.Nm
backend in use by default is determined in a platform-specific
way.
To register or select a specific backend,
.Fn AG_SetUserOps
may be used.
.\" MANLINK(AG_UserOps)
.Sh BACKEND INTERFACE
The argument to
.Fn AG_SetUserOps
should point to the following structure:
.Bd -literal
typedef struct ag_user_ops {
	const char *name;                   /* Name for this backend */
	void     (*init)(void);
	void     (*destroy)(void);
	int      (*getUserByName)(AG_User *, const char *);
	int      (*getUserByUID)(AG_User *, Uint32);
	int      (*getRealUser)(AG_User *);
	int      (*getEffectiveUser)(AG_User *);
} AG_UserOps;
.Ed
.Pp
.Fn init
performs any necessary initialization.
.Fn destroy
cleans up any allocated resources.
.Pp
On success, the query methods
.Fn getUserByName ,
.Fn getUserByUID ,
.Fn getRealUser
and
.Fn getEffectiveUser
should set the fields of the
.Ft AG_User
argument and return 0.
On error, they should return -1.
.Sh SEE ALSO
.Xr AG_File 3 ,
.Xr AG_Intro 3
.Sh HISTORY
The
.Nm
interface first appeared in Agar 1.5.0.
The "getenv" module was added in Agar 1.6.0.
